Constants

ERROR_READ_ONLY

ERROR_READ_ONLY = 1

ERROR_NO_CONNECTION

ERROR_NO_CONNECTION = 2

ERROR_VALIDATE

ERROR_VALIDATE = 3

ERROR_SAVING

ERROR_SAVING = 4

SEARCH_ALL

SEARCH_ALL = 0

SEARCH_STRICT

SEARCH_STRICT = 1

SEARCH_PREFIX

SEARCH_PREFIX = 2

SEARCH_GROUPS

SEARCH_GROUPS = 4

TYPE_CONTACT

TYPE_CONTACT = 0

TYPE_RECIPIENT

TYPE_RECIPIENT = 1

TYPE_TRUSTED_SENDER

TYPE_TRUSTED_SENDER = 2

TYPE_DEFAULT

TYPE_DEFAULT = 4

TYPE_WRITEABLE

TYPE_WRITEABLE = 8

TYPE_READONLY

TYPE_READONLY = 16

SEPARATOR

SEPARATOR = ','

Properties

$primary_key

$primary_key : string

Type

string — Name of the primary key field of this addressbook. Used to search for previously retrieved IDs.

$groups

$groups : bool

Type

bool — True if the addressbook supports contact groups.

$export_groups

$export_groups : bool

Type

bool — True if the addressbook supports exporting contact groups. Requires the implementation of get_record_groups().

$readonly

$readonly : bool

Type

bool — True if the addressbook is read-only.

$searchonly

$searchonly : bool

Type

bool — True if the addressbook does not support listing all records but needs use of the search function.

$undelete

$undelete : bool

Type

bool — True if the addressbook supports restoring deleted contacts.

$ready

$ready : bool

Type

bool — True if the addressbook is ready to be used. See rcmail_action_contacts_index::$CONTACT_COLTYPES

$group_id

$group_id : null|string|int

Type

null|string|int — If set, addressbook-specific identifier of the selected group. All contact listing and contact searches will be limited to contacts that belong to this group.

$list_page

$list_page : int

Type

int — The current page of the listing. Numbering starts at 1.

$page_size

$page_size : int

Type

int — The maximum number of records shown on a page.

$sort_col

$sort_col : string

Type

string — Contact field by which to order listed records.

$sort_order

$sort_order : string

Type

string — Whether sorting of records by $sort_col is done in ascending (ASC) or descending (DESC) order.

$date_cols

$date_cols : string[]

Type

string[] — A list of record fields that contain dates.

$coltypes

$coltypes : array

Type

array — Definition of the contact fields supported by the addressbook.

$vcard_map

$vcard_map : string[]

Type

string[] — vCard additional fields mapping

$name

$name

$error

$error : ?array

Type

?array — Error state - hash array with the following fields: type, message

$db_name

$db_name

$db_groups

$db_groups

$db_groupmembers

$db_groupmembers

$vcard_fieldmap

$vcard_fieldmap

$db

$db : \rcube_db

Store database connection.

Type

rcube_db

$user_id

$user_id

$filter

$filter

$result

$result

$cache

$cache

$table_cols

$table_cols

$fulltext_cols

$fulltext_cols

Methods

get_name()

get_name() : string

Returns addressbook name

Returns

string —

set_search_set()

set_search_set(string  $filter) : void

Save a search string for future listings

Parameters

string $filter

SQL params to use in listing method

get_search_set()

get_search_set() : mixed

Getter for saved search properties

Returns

mixed —

Search properties used by this class

reset()

reset() : void

Reset all saved results and search parameters

refresh_search()

refresh_search() : mixed

Refresh saved search set after data has changed

Returns

mixed —

New search set

list_records()

list_records(mixed  $cols = null, mixed  $subset, mixed  $nocount = false) : array

List the current set of contact records

Parameters

mixed $cols

List of columns to include in the returned records (null means all)

mixed $subset

Only return this number of records of the current page, use negative values for tail

mixed $nocount

True to skip the count query (select only)

Returns

array —

Indexed list of contact records, each a hash array

search()

search(mixed  $fields, mixed  $value, int  $mode, bool  $select = true, bool  $nocount = false, array  $required = []) : \rcube_result_set

Search contacts

Parameters

mixed $fields

The field name or array of field names to search in

mixed $value

Search value (or array of values when $fields is array)

int $mode

Search mode. Sum of rcube_addressbook::SEARCH_*

bool $select

True if results are requested, False if count only

bool $nocount

True to skip the count query (select only)

array $required

List of fields that cannot be empty

Returns

\rcube_result_set —

Contact records and 'count' value

count()

count() : \rcube_result_set

Count number of available contacts in database

Returns

\rcube_result_set —

Result object

get_result()

get_result() : mixed

Return the last result set

Returns

mixed —

Result array or NULL if nothing selected yet

get_record()

get_record(mixed  $id, bool  $assoc = false) : \rcube_result_set|array

Get a specific contact record

Parameters

mixed $id

Record identifier(s)

bool $assoc

Enables returning associative array

Returns

\rcube_result_set|array —

Result object with all record fields

get_error()

get_error() : ?array

Returns the last error occurred (e.g. when updating/inserting failed)

Returns

?array —

Hash array with the following fields: type, message. Null if no error set.

close()

close() : mixed

Close connection to source Called on script shutdown

Returns

mixed —

set_page()

set_page(int  $page) : mixed

Set internal list page

Parameters

int $page

Page number to list

Returns

mixed —

set_pagesize()

set_pagesize(int  $size) : mixed

Set internal page size

Parameters

int $size

Number of messages to display on one page

Returns

mixed —

set_sort_order()

set_sort_order(?string  $sort_col, ?string  $sort_order = null) : mixed

Set internal sort settings

Parameters

?string $sort_col

Sort column

?string $sort_order

Sort order

Returns

mixed —

validate()

validate(array  $save_data, bool  $autofix = false) : bool

Check the given data before saving.

If input not valid, the message to display can be fetched using get_error()

Parameters

array $save_data

Associative array with data to save

bool $autofix

Try to fix/complete record automatically

Returns

bool —

True if input is valid, False if not.

insert()

insert(array  $save_data, bool  $check = false) : int|bool

Create a new contact record

Parameters

array $save_data

Associative array with save data

bool $check

Enables validity checks

Returns

int|bool —

The created record ID on success, False on error

insertMultiple()

insertMultiple(\rcube_result_set  $recset, bool  $check = false) : array

Create new contact records for every item in the record set

Parameters

\rcube_result_set $recset

Recordset to insert

bool $check

True to check for duplicates first

Returns

array —

List of created record IDs

update()

update(mixed  $id, array  $save_cols) : bool

Update a specific contact record

Parameters

mixed $id

Record identifier

array $save_cols

Associative array with save data

Returns

bool —

True on success, False on error

delete()

delete(array  $ids, bool  $force = true) : int|false

Mark one or more contact records as deleted

Parameters

array $ids

Record identifiers

bool $force

Remove record(s) irreversible (unsupported)

Returns

int|false —

Number of removed records, False on failure

undelete()

undelete(array  $ids) : int

Undelete one or more contact records

Parameters

array $ids

Record identifiers

Returns

int —

Number of undeleted contact records

delete_all()

delete_all(bool  $with_groups = false) : int

Remove all records from the database

Parameters

bool $with_groups

Remove also groups

Returns

int —

Number of removed records

set_group()

set_group(mixed  $gid) : mixed

Setter for the current group (empty, has to be re-implemented by extending class)

Parameters

mixed $gid

Returns

mixed —

list_groups()

list_groups(string  $search = null, int  $mode) : array

List all active contact groups of this source

Parameters

string $search

Search string to match group name

int $mode

Matching mode. Sum of rcube_addressbook::SEARCH_*

Returns

array —

Indexed list of contact groups, each a hash array

get_group()

get_group(string  $group_id) : ?array

Get group properties such as name and email address(es)

Parameters

string $group_id

Group identifier

Returns

?array —

Group properties as hash array, null in case of error.

create_group()

create_group(string  $name) : array|false

Create a contact group with the given name

Parameters

string $name

The group name

Returns

array|false —

False on error, array with record props in success

delete_group()

delete_group(string  $gid) : bool

Delete the given group (and all linked group members)

Parameters

string $gid

Group identifier

Returns

bool —

True on success, false if no data was changed

rename_group()

rename_group(string  $gid, string  $name, string  $new_gid) : string|false

Rename a specific contact group

Parameters

string $gid

Group identifier

string $name

New name to set for this group

string $new_gid

(not used)

Returns

string|false —

New name on success, false if no data was changed

add_to_group()

add_to_group(mixed  $group_id, mixed  $ids) : int

Add the given contact records the a certain group

Parameters

mixed $group_id

Group identifier

mixed $ids

List of contact identifiers to be added

Returns

int —

Number of contacts added

remove_from_group()

remove_from_group(string  $group_id, array|string  $ids) : int

Remove the given contact records from a certain group

Parameters

string $group_id

Group identifier

array|string $ids

List of contact identifiers to be removed

Returns

int —

Number of deleted group members

get_record_groups()

get_record_groups(mixed  $id) : array

Get group assignments of a specific contact record

Parameters

mixed $id

Record identifier

Returns

array —

List of assigned groups, indexed by a group ID

get_col_values()

get_col_values(string  $col, array  $data, bool  $flat = false) : array

Utility function to return all values of a certain data column either as flat list or grouped by subtype

Parameters

string $col

Col name

array $data

Record data array as used for saving

bool $flat

True to return one array with all values, False for hash array with values grouped by type

Returns

array —

List of column values

compose_display_name()

compose_display_name(array  $contact, bool  $full_email = false) : string

Compose a valid display name from the given structured contact data

Parameters

array $contact

Hash array with contact data as key-value pairs

bool $full_email

Don't attempt to extract components from the email address

Returns

string —

Display name

compose_list_name()

compose_list_name(array  $contact) : string

Compose the name to display in the contacts list for the given contact record.

This respects the settings parameter how to list contacts.

Parameters

array $contact

Hash array with contact data as key-value pairs

Returns

string —

List name

compose_search_name()

compose_search_name(array  $contact, string  $email = null, string  $name = null, string  $templ = null) : string

Build contact display name for autocomplete listing

Parameters

array $contact

Hash array with contact data as key-value pairs

string $email

Optional email address

string $name

Optional name (self::compose_list_name() result)

string $templ

Optional template to use (defaults to the 'contact_search_name' config option)

Returns

string —

Display name

compose_contact_key()

compose_contact_key(array  $contact, string  $sort_col) : string

Create a unique key for sorting contacts

Parameters

array $contact

Contact record

string $sort_col

Sorting column name

Returns

string —

Unique key

__construct()

__construct(object  $dbconn, int  $user) : mixed

Object constructor

Parameters

object $dbconn

Instance of the rcube_db class

int $user

User-ID

Returns

mixed —

set_error()

set_error(int  $type, string  $message) : mixed

Setter for errors for internal use

Parameters

int $type

Error type (one of this class' error constants)

string $message

Error message (name of a text label)

Returns

mixed —

compare_search_value()

compare_search_value(string  $colname, string|array  $value, string  $search, int  $mode) : bool

Compare search value with contact data

Parameters

string $colname

Data name

string|array $value

Data value

string $search

Search value

int $mode

Search mode

Returns

bool —

Comparison result

fulltext_sql_where()

fulltext_sql_where(mixed  $value, mixed  $mode, mixed  $col = 'words', mixed  $bool = 'AND') : mixed

Helper method to compose SQL where statements for fulltext searching

Parameters

mixed $value
mixed $mode
mixed $col
mixed $bool

Returns

mixed —

_count()

_count() : int

Count number of available contacts in database

Returns

int —

Contacts count

convert_db_data()

convert_db_data(mixed  $sql_arr) : mixed

Convert data stored in the database into output format

Parameters

mixed $sql_arr

Returns

mixed —

convert_save_data()

convert_save_data(mixed  $save_data, mixed  $record = []) : mixed

Convert input data for storing in the database

Parameters

mixed $save_data
mixed $record

Returns

mixed —

unique_groupname()

unique_groupname(string  $name) : string

Check for existing groups with the same name

Parameters

string $name

Name to check

Returns

string —

A group name which is unique for the current use